/**
 * @file score_engine.h
 * @brief Multi-dimensional scoring engine public header file
 * @brief 多维度评分引擎公共头文件
 * 
 * This header file defines the public interfaces and data structures for the scoring engine
 * 此头文件定义了评分引擎的公共接口和数据结构
 */

#ifndef SCORE_ENGINE_H
#define SCORE_ENGINE_H

#ifdef __cplusplus
extern "C" {
#endif

// Score dimension enable flags
// 评分维度启用标志
typedef enum {
    // Existing scoring dimensions
    // 已有的评分维度
    SCORE_PITCH      = 0x00000001,   // Pitch scoring // 音高评分
    SCORE_BRIGHTNESS = 0x00000002,   // Brightness scoring // 亮度评分
    SCORE_RHYTHM     = 0x00000004,   // Rhythm scoring // 节奏评分
    SCORE_EMOTION    = 0x00000008,   // Emotion scoring // 情感评分
    SCORE_BREATH     = 0x00000010,   // Breath scoring // 气息评分
    SCORE_TIMBRE     = 0x00000020,   // Timbre scoring // 音色评分
    
    // Reserved expansion space
    // 预留扩展位
    SCORE_RESERVED_1 = 0x00000040,   // Reserved position 1 // 预留位置1
    SCORE_RESERVED_2 = 0x00000080,   // Reserved position 2 // 预留位置2
    SCORE_RESERVED_3 = 0x00000100,   // Reserved position 3 // 预留位置3
    
    // Special flags
    // 特殊标志
    SCORE_CUSTOM     = 0x40000000,   // Custom scoring dimension flag // 自定义评分维度标志
    SCORE_ALL        = 0x0000003F    // All basic scoring dimensions // 所有基础评分维度
} ScoreDimensionFlags;

// Basic weight definitions for each scoring dimension (corresponding to song style)
// 各评分维度的基础权重定义（对应歌曲风格）
typedef struct {
    float pitch_weight;      // Pitch weight // 音高权重
    float brightness_weight; // Brightness weight (used for technique weight in this version) // 亮度权重（本版本中用于技巧权重）
    float rhythm_weight;     // Rhythm weight // 节奏权重
    float emotion_weight;    // Emotion weight // 情感权重
    float breath_weight;     // Breath weight // 气息权重
    float timbre_weight;     // Timbre weight (set to 0, unused) // 音色权重（设为0，未使用）
} ScoreWeights;

// Difficulty factor structure (corresponding to difficulty level)
// 难度因子结构体（对应难度等级）
typedef struct {
    float pitch_tolerance;    // Pitch tolerance, higher value is more forgiving // 音高容忍度，值越高越宽松
    float rhythm_tolerance;   // Rhythm tolerance // 节奏容忍度
    float other_tolerances;   // Other dimension tolerances // 其他维度容忍度
} DifficultyFactors;

// Song style enumeration
// 歌曲风格枚举
typedef enum {
    SONG_STYLE_POP,       // Pop song // 流行歌曲
    SONG_STYLE_ROCK,      // Rock song // 摇滚歌曲
    SONG_STYLE_FOLK,      // Folk song // 民谣歌曲
    SONG_STYLE_RAP,       // Rap music // 说唱音乐
    SONG_STYLE_RNB,       // R&B music // R&B音乐
    SONG_STYLE_CLASSICAL, // Classical music // 古典音乐
    SONG_STYLE_JAZZ,      // Jazz music // 爵士音乐
    SONG_STYLE_ELECTRONIC,// Electronic music // 电子音乐
    SONG_STYLE_CUSTOM     // Custom style // 自定义风格
} SongStyle;

// Difficulty level enumeration
// 难度等级枚举
typedef enum {
    DIFFICULTY_EASY,      // Easy difficulty // 简单难度
    DIFFICULTY_NORMAL,    // Normal difficulty // 普通难度
    DIFFICULTY_HARD,      // Hard difficulty // 困难难度
    DIFFICULTY_EXPERT,    // Expert difficulty // 专家难度
    DIFFICULTY_CUSTOM     // Custom difficulty // 自定义难度
} DifficultyLevel;

// Scoring engine configuration options
// 评分引擎配置选项
typedef struct {
    unsigned int enabled_dimensions; // Enabled scoring dimensions // 启用的评分维度
    SongStyle style;              // Song style // 歌曲风格
    DifficultyLevel difficulty;   // Difficulty level // 难度等级
    ScoreWeights* custom_weights; // Custom weights (use preset weights if NULL) // 自定义权重（如果为NULL，则使用预设权重）
    DifficultyFactors* custom_factors; // Custom difficulty factors (use preset difficulty if NULL) // 自定义难度因子（如果为NULL，则使用预设难度）
} ScoreEngineConfig;

// Scoring engine context structure
// 评分引擎上下文结构体
typedef struct {
    void* base_file;         // Base file pointer // 基准文件指针
    int frame_size;          // Audio frame size (must match hop_size in base file) // 音频帧大小（必须与基准文件中的hop_size匹配）
    int sample_rate;         // Sample rate (must match sample_rate in base file) // 采样率（必须与基准文件中的sample_rate匹配）
    void* internal_state;    // Internal state data // 内部状态数据
    long  data_offset;       // Offset (bytes) from file start to frame data section //数据区偏移量(打分条数据)
} ScoreEngine;

// Detailed score structure (single frame features)
// 详细得分结构（单帧特征）
typedef struct {
    int frame_index;             // Frame index // 帧索引
    float vad_value;             // Current frame VAD value (Voice Activity Detection), range 0.0-1.0 // 当前帧VAD值（人声活动检测），范围0.0-1.0
    float energy;                // Current frame energy value // 当前帧能量值
    float pitch;                 // Pitch value // 音高值
    float brightness;            // Brightness value // 亮度值
    float timbre;                // Timbre value // 音色值
} FrameFeature;

// Complete score result structure
// 完整评分结果结构体
typedef struct {
    // Overall scores (0-100)
    // 总分 (0-100)
    int score_flag;          // Score update flag // 分数更新标志
    int overall_score;       // Overall total score // 综合总分
    int pitch_score;         // Pitch total score // 音高总分
    int brightness_score;    // Brightness total score (used for technique score in this version) // 亮度总分（本版本中用于技巧分）
    int rhythm_score;        // Rhythm total score // 节奏总分
    int emotion_score;       // Emotion total score // 情感总分
    int breath_score;        // Breath total score // 气息总分
    int timbre_score;        // Timbre total score (unused, set to 0) // 音色总分（未使用，设为0）
    
    int total_frames;        // Total frames // 总帧数
    FrameFeature frame_feature;  // Current frame features // 当前帧特征
    FrameFeature base_frame_feature;  // Base frame features // 基准文件帧特征
} ScoreResult;

// Scoring engine error code definitions
// 评分引擎错误码定义
typedef enum {
    // Success
    // 成功
    ERROR_SUCCESS                = 0,    // Operation successful // 操作成功
    
    // Initialization errors (1-99)
    // 初始化错误 (1-99)
    ERROR_FILE_NOT_FOUND         = 1,    // File not found // 文件未找到
    ERROR_FILE_CORRUPT           = 2,    // File corrupt // 文件损坏
    ERROR_FILE_VERSION_MISMATCH  = 3,    // File version mismatch // 文件版本不匹配
    ERROR_FRAME_SIZE_MISMATCH    = 4,    // Frame size mismatch // 帧大小不匹配
    ERROR_SAMPLE_RATE_MISMATCH   = 5,    // Sample rate mismatch // 采样率不匹配
    ERROR_CONFIG_INVALID         = 6,    // Invalid configuration // 无效配置
    ERROR_OUT_OF_MEMORY          = 7,    // Out of memory // 内存不足
    ERROR_MEMORY_ALLOC_FAILED    = 8,    // Memory allocation failed // 内存分配失败

    // Audio processing errors (100-199)
    // 音频处理错误 (100-199)
    ERROR_ENGINE_NOT_INITIALIZED = 101,  // Engine not initialized // 引擎未初始化
    ERROR_AUDIO_FRAME_INVALID    = 102,  // Invalid audio frame // 无效音频帧
    ERROR_AUDIO_PROCESSING       = 105,  // Audio processing error // 音频处理错误
  
    ERROR_UNKNOWN                = 999   // Unknown error // 未知错误
} ErrorCode;

/**
 * @brief Initialize scoring engine
 * @brief 初始化评分引擎
 * 
 * @param base_file Base file data / 基准文件数据
 * @param frame_size Set audio frame size / 设置音频帧大小
 * @param frame_size Set audio frame size // 设置音频帧大小
 * @param sample_rate Audio sample rate // 音频采样率
 * @param config Scoring engine configuration options, such as song style and difficulty level (use default configuration if NULL) // 评分引擎配置选项，如歌曲风格和难度等级（如果为NULL，则使用默认配置）
 * @return ScoreEngine* Scoring engine context, returns NULL on failure // 评分引擎上下文，失败时返回NULL
 */
ScoreEngine* init_score_engine(const void* base_file, size_t data_size, int frame_size, int sample_rate, const ScoreEngineConfig* config);

/**
 * @brief Get error code when initialization returns NULL
 * @brief 获取初始化返回NULL时的错误码
 * 
 * @return int Returns 0 on success, error code on failure // 成功返回0，失败返回错误码
 */
int get_init_error(void);

/**
 * @brief Real-time scoring interface function
 * @brief 实时评分接口函数
 * 
 * @param engine Scoring engine context // 评分引擎上下文
 * @param audioFrame Input audio data // 输入的音频数据
 * @param frameIndex Current frame index // 当前帧索引
 * @param result Score result output // 评分结果输出
 * @param spectrum Spectrum data, fixed 512 points, first 256 for reference spectrum, last 256 for current frame spectrum // 频谱数据，固定512点，前256为参考谱，后256为当前帧谱
 * @return int Returns 0 on success, error code on failure // 成功返回0，失败返回错误码
 */
int score_audio_frame(ScoreEngine* engine, const float* audioFrame, int frameIndex, ScoreResult* result, float* spectrum);

/**
 * @brief Release scoring engine resources
 * @brief 释放评分引擎资源
 * 
 * @param engine Scoring engine context // 评分引擎上下文
 */
void release_score_engine(ScoreEngine* engine);

#ifdef __cplusplus
}
#endif

#endif /* SCORE_ENGINE_H */